C/C++ Users Group Library 1996 July

home *** CD-ROM | disk | FTP | other *** search

/ C/C++ Users Group Library 1996 July / C-C++ Users Group Library July 1996.iso / vol_400 / 428_01 / pictor.doc < prev next >

Wrap

Text File | 1994-03-13 | 172.8 KB | 4,370 lines

PICTOR Video Library User's Guide and Reference For IBM (R) personal computers and 100% compatibles PICTOR User's Guide and Reference SoftCircuits and PICTOR are trademarks of SoftCircuits. All other brands and product names are trademarks or registered trademarks of their respective holders. PICTOR Video Library, Version 1.51 Copyright (c) 1992-94 SoftCircuits. Redistributed by permission. PICTOR was designed and written by Jonathan Wood. SoftCircuits Programming P.O. Box 16262 Irvine, CA 92713 U.S.A. 2 PICTOR User's Guide and Reference COPYRIGHTED MATERIAL --------------------------------------------------------------- This product (source code, object code, supporting programs, and documentation) is protected by United States copyright law as well as international copyright treaty provisions. SoftCircuits is releasing this product to be used and distributed free of charge, providing that SoftCircuits retains its copyright, and receives credit for the work done in this product's creation. In keeping with the above, SoftCircuits grants to you the following rights: 1. You may make any number of copies of the source code, object code, and supporting programs, for your own use or to be distributed to others, provided that you distribute them in the original, unmodified form, complete with all files, copyrights notices, etc, and that no fee is charged for such distribution except for reasonable media and shipping charges. 2. You may modify the copyrighted source code, object code, and supporting programs in connection with your use of this product. However, under copyright law, the modified source code and resulting object code remain the copyrighted property of SoftCircuits, regardless of the extent of the modifications. Therefore, you may not alter or remove any copyright notices or similar proprietary rights notices from any portion of this product. 3. You may also incorporate any of the copyrighted object code in executable form into your own programs, and you may use and distribute these programs royalty free, provided that all of the following requirements are satisfied: a. All copies of such programs must bear a copyright notice, and the form of the notice must not detract from SoftCircuits' copyright in any way. Your own copyright notice is sufficient if it consists entirely of the following: the word "Copyright", the years(s) of publication of the program, and your name (or your company name). b. Such programs must not substantially duplicate the overall functionality of this product or any portion thereof. c. You must assume full and complete responsibility and liability for the operation of these programs, including testing of all included object code to ensure that it functions as documented and/or as expected or required. Except as described above, you may not legally copy or distribute the documentation, source code, object code, or supporting programs, in whole or in part. All rights not specifically granted above are reserved by SoftCircuits. 3 PICTOR User's Guide and Reference SOFTCIRCUITS SPECIFICALLY DISCLAIMS ALL WARRANTIES, INCLUDING, WITHOUT LIMITATION, ALL IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT OF THIRD PARTY RIGHTS. UNDER NO CIRCUMSTANCES WILL SOFTCIRCUITS BE LIABLE FOR SPECIAL, INCIDENTAL, CONSEQUENTIAL, INDIRECT, OR ANY OTHER DAMAGES OR CLAIMS ARISING FROM THE USE OF THIS PRODUCT, INCLUDING LOSS OF PROFITS OR ANY OTHER COMMERCIAL DAMAGES, EVEN IF WE HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. IN NO EVENT WILL SOFTCIRCUITS BE LIABLE FOR ANY CLAIMS, LIABILITY, OR DAMAGES ARISING FROM CHANGES MADE BY YOU TO THE SOURCE CODE, OBJECT CODE, OR SUPPORTING PROGRAMS. 4 PICTOR User's Guide and Reference INTRODUCTION ----------------------------------------------------------------- Pictor (pik'ter) [L, painter] a constellation between Carina and Dorado. PICTOR is a powerful video library designed for text-mode applications written in C running on IBM personal computers and 100% compatibles. Features of the package include: * Multi-pane stacked windows. * Complete pulldown menu system. * Complete hypertext help system and help compiler. * Interrupt-driven serial communications routines. * Ctrl-C, Ctrl-Break, and critical error handling. On screen Clock. * Text compression routines. * Text editor sample application that edits files up to available memory. * All source code is included. * Over 100 highly granular high-level and low-level routines provide complete control over display and keyboard. The library provides many high level routines, most of which can easily be implemented in just one or two function calls. For example, the Ctrl-C, Ctrl-Break and critical error handlers are all installed (and will all uninstall automatically) with a single function call. The library also provides many low-level functions that provide support for custom routines that you create. This package includes two sets of libraries: one for Microsoft C 7.0 and another for Borland C 3.0. Wherever practical, the library routines are ANSI C compatible; therefore, the library will link with programs compiled with C compilers from most other vendors with little or no modifications. Please read the README.DOC file on the distribution disk(s). It contains last minute additions and corrections to the manual. This file also has notes about working with the source code. Refer to the file FILELIST.DOC for a list and description of all the files on the distribution disk(s). USING PICTOR ----------------------------------------------------------------- This section describes the key elements of the PICTOR library. Refer to the function reference section for a comprehensive description of all functions and macros. Getting Started To install PICTOR on your system, you can use the INSTALL.EXE program included with this package. Since none of the files on the distribution disk(s) are compressed, you do not need to use 5 PICTOR User's Guide and Reference this program. You might prefer to simply copy the files as you need them. To start the installation program, make the drive that contains the distribution disk(s) the active drive and enter the following command at the DOS prompt: INSTALL The installation program's main menu contains the following three selections: Selection Description ------------------------------------------------------------- Set Install Options This selection allows you to select which elements of the PICTOR package you want to install. Set Install Directories This selection lets you specify the directories where the library will be installed. We recommend installing the libraries and include files in your compiler's library and include directories. Begin Installation This selection begins the installation process. The installation program will copy the selected files to the specified directories. Once PICTOR is installed, you can incorporate PICTOR functions into your program by linking your program with the library that matches the memory model and compiler that you are using. The library names for each memory model and compiler are as follows: Library Name Memory Model and Compiler ------------------------------------------------------------ PICTORSM.LIB Small and tiny memory models for Microsoft C and Quick C. PICTORMM.LIB Medium memory model for Microsoft C and Quick C. PICTORCM.LIB Compact memory model for Microsoft C and Quick C. PICTORLM.LIB Large and huge memory models for Microsoft C and Quick C. PICTORSB.LIB Small and tiny memory models for Borland C and Turbo C. PICTORMB.LIB Medium memory model for Borland C and Turbo C. PICTORCB.LIB Compact memory model for Borland C and Turbo C. PICTORLB.LIB Large and huge memory models for Borland C and Turbo C. If you are compiling from the command line, be sure that the library is passed to the linker as a library and not linked in as an object module. The library is highly granular so only the 6 PICTOR User's Guide and Reference routines your program uses will be linked into your executable file; however, linking with a library as an object module will place the entire library into your program. You should include the appropriate header file(s) in your source code to insure proper type-checking of function arguments and return values. The function reference section lists the appropriate include file for each function or macro. We recommend putting the include files in your compiler's include directory. Refer to your C compiler's documentation for information about the library and include directories and how to access the files in those directories. IMPORTANT: All programs that use PICTOR library functions to access the display should begin by calling the initvideo function. initvideo determines the type of display adapter that is active and sets several internal variables accordingly. You can then use getvconfig to return information about the current display configuration if your application needs it. PICTOR Windows PICTOR library functions that write to the display can be divided into two groups: those that are screen oriented and those that are window oriented. The screen oriented functions can be used to write anywhere on the screen. Window oriented functions restrict output to within the active window pane. PICTOR provides a stacked windowing system. Stacked windows created with wopen remain on top of all previously created windows until they are closed using wclose. While this method has limitations, it provides the easiest possible interface for your applications. PICTOR windows can have multiple window panes. Window panes are window subdivisions that are created using wpane, and made active with setwpane. A window always has at least one window pane and can have as many as the window's size and system memory will allow. Using the Cursor Within the library, there are actually three types of cursors: the hardware text cursor, the screen's logical cursor, and the active window pane's logical cursor. The hardware text cursor is the visible, blinking cursor that you normally see when using text-mode applications. The screen and active window pane's logical cursors are not really cursors at all; they are values maintained internally by the library to specify where screen writes will occur. PICTOR library routines that write to the screen pay no attention to the location of the hardware text cursor. The PICTOR library's use of cursors may be a little confusing at first if you are used to always writing to the screen at the position of the hardware text cursor. Since the library routines write directly to display memory, it would be additional overhead for those functions to always program the hardware text cursor. 7 PICTOR User's Guide and Reference Many parts of the library (such as the menu system) simply position the hardware text cursor off the screen while the user makes selections by moving highlight bars and pressing hotkeys. The functions and macros for working with the different cursors are listed in the following table: Function Description -------------------------------------------------------------- getcurs Returns the current row and column position of the hardware text cursor. getcurscol Returns the current column position of the hardware text cursor. getcursrow Returns the current row position of the hardware text cursor. getcurstype Returns the hardware text cursor's starting and ending scan line values. getvcol Returns the current column position of the screen's logical cursor position. getvrow Returns the current row position of the screen's logical cursor position. getwcol Returns the current column position of the active window pane's logical cursor position. getwrow Returns the current row position of the active window pane's logical cursor position. popcurs Restores the hardware text cursor to the position and type it was prior to the last call to pushcurs. pushcurs Saves the current hardware text cursor position and type so that it can later be restored with popcurs. setcurs Sets the position of the hardware text cursor. setcurstype Sets the starting and ending scan lines of the hardware text cursor. setvpos Sets the screen's logical cursor position. setwpos Sets the active window pane's logical cursor position. showcurs Hides or restores the hardware text cursor. synccurs Sets the position of the hardware text cursor to match the current screen's logical cursor position. syncvpos Sets the screen's logical cursor position to match the current position of the hardware text cursor. wsynccurs Sets the position of the hardware text cursor to match the active window pane's logical cursor position. All cursor coordinates are 1-based so 1, 1 specifies the top, left corner of the cursor's respective region. Displaying Colors The PICTOR library provides complete control over screen colors. The following color constants are defined in PICTOR.H: 8 PICTOR User's Guide and Reference BLACK BLUE GREEN CYAN RED MAGENTA YELLOW WHITE BOLD BLINKING PICTOR functions that accept color specifiers require that the foreground and background arguments are combined into a single color value. The foreback macro can be used to combine foreground and background arguments into a value that can be passed to PICTOR functions. All of the color constants listed above can be used as either foreground or background arguments except for BOLD and BLINKING. BOLD and BLINKING are only valid when combined with foreground arguments using + or |. For example, the following statement uses vcolor to set the current color attribute to bold white characters on a blue background. vcolor(foreback(BOLD+WHITE,BLUE)); In addition, some library functions (such as runmenu and messagebox) use several color attributes to display hotkeys and highlight bars. These functions take a pointer to a COLORSTRUCT structure. This structure contains the following members: Member Description ---------------------------------------------- int normal Normal text. int boldnormal Bold normal text. int select Selected text. int boldselect Bold selected text. When writing your application, you should remember that some users may not use a color display. You can use the getvconfig function to determine if the active display supports color and set your program's color attributes accordingly. Creating Menus The PICTOR library includes a complete menuing subsystem. Incorporating menus into your application requires two steps: creating your application's menu data structures, and placing a call to runmenu in your application's main loop (or one of the main loops). The menu data structures contain the information that appears in the menus and defines which functions will be called if the user selects the corresponding menu selection. Optionally, they can also contain information to be displayed on the status bar when an item is highlighted, and can include a help topic string that will be passed to helprun if the user presses <F1> when that item is highlighted. Each pulldown submenu is defined as an array of SUBMENU structures. This structure contains the following members: Member Description ---------------------------------------------- char *item The text that appears as the submenu selection. 9 PICTOR User's Guide and Reference char *description The text that appears on the status bar when this selection is highlighted. (Use NULL for none.) char *helptopic A pointer to a help topic string to be sent to helprun if the user presses <F1> when this selection is highlighted. void (*function)(void) A pointer to the function to be called if the user selects this selection. You can use the constant SUBMENU_DIVIDER (defined in PICTOR.H) as one or more of the array elements. This constant creates a dividing bar that can be used to separate non-related menu items. IMPORTANT: The last structure in the array must be the constant END_SUBMENU (also defined in PICTOR.H). This constant signifies the end of the submenu array. When you have defined your submenus, you are ready to create the mainmenu that references each of those submenus. A mainmenu is created with an array of MAINMENU structures. This structure contains the following members: Member Description --------------------------------------------- char *item The text that appears as the menu selection. char *description The text that appears on the status bar when this selection is highlighted. (Use NULL for none.) char *helptopic A pointer to a help topic string to be sent to helprun if the user presses <F1> when this selection is highlighted. SUBMENU *submenu A pointer to the submenu (pulldown menu) to be activated if the user selects this selection. IMPORTANT: The last structure in the mainmenu array must be the constant END_MAINMENU (also defined in PICTOR.H). This constant signifies the end of the mainmenu array. For both the SUBMENU and MAINMENU structures, the string in the item field can contain embedded hotkeys. A hotkey is a bold letter within a string that can be used to select the item associated with that string. You can embed hotkeys by preceding the character you want to be the hotkey with the tilde character (~). (Note that the tilde character is not displayed in the menu.) Hotkeys in the mainmenu can be used to select a submenu (mainmenu hotkeys are used in combination with the Alt key when the menu is not active). Hotkeys in the submenu can be used to select submenu selections. For example, if one of your submenus is called the "File" menu, and you want the first letter (F) to be the hotkey, the item string in the MAINMENU structure might appear as: 10 PICTOR User's Guide and Reference "~File" The main menu function_runmenu_works somewhat like kbdread because it returns the keyboard code for the next available keystroke. However, if the next keystroke is relevant to the current menu, the keystroke is processed by runmenu and runmenu returns 0. If runmenu returns the keystroke (a non-zero value), your program can process the keystroke. By placing the call to runmenu within your program's main loop (or one of its main loops), the menu becomes an integrated part of your application. In addition, you can use the showmenu function to display a menu when your application paints the screen. To see an example program that shows how to use runmenu, see the example for runmenu in the function reference section. Although the library provides no direct support for adding and removing menu selections, it would be easy to implement such a feature. Since runmenu takes a pointer to a menu data structure, you can simple modify this data. In fact, you could easily create an application with context-sensitive menus by defining several menus and passing different ones to runmenu at different locations in your program. Creating On-line Help This package provides a complete hypertext help system and help compiler. Being hypertext means that you can embed links within the help text. A link is a reference to another help topic, usually displayed with bold attributes. The user can select a link to view the topic it references. A help database can be built with many links between topics that allows the user to easily traverse between related topics. The first step in creating on-line help is to write the help text. The help compiler requires that the text follows a simple set of syntax rules so that the compiler can generate the required information. Help compiler directives begin with the '@' character. In this version of the help compiler, only two directives are supported: @BEGIN and @END. @BEGIN defines the beginning of a help topic and is followed on the same line by a label that names the topic. The label may be one or more words. The @END directive marks the end of a help topic. Compiler directives must always be the first non-space characters on the line, and are not case sensitive. Links are defined by placing text between two vertical bars (|). The text should match a @BEGIN label defined elsewhere in the help file. The text is not case sensitive but must match character for character with the referenced topic label. Note that the vertical bar characters are not displayed in the help window. Also note that the starting and ending vertical bar must be on the same line. 11 PICTOR User's Guide and Reference Each line outside @BEGIN/@END directives that has a semicolon (;) as the first non-space character is considered a comment and is ignored by the help compiler. Blank lines outside @BEGIN/@END directives are also ignored. Here is a short example of a help text file: ; ; This line is a comment and is ignored by the help compiler ; @BEGIN Apples Apples can be red or green. Like other |Fruit|, apples grow on trees. @END @BEGIN Bananas Bananas are always yellow unless they are not yet ripe. For another tasty fruit, see |Apples|. @END @BEGIN Fruit Fruit grows on trees and is usually sweet to the taste. Some examples of fruit are |Apples| and |Bananas|. @END This example defines three help topics: "Apples", which contains a hypertext link to "Fruit"; "Bananas", which contains a link to "Apples"; and "Fruit", which contains links to both "Apples" and "Bananas". The next step is to compile the help text using the help compiler (HC.EXE). The help compiler has many warning and error messages to help pinpoint any syntax errors in the input file. The compiler uses the text compression routines included in the PICTOR library. This results in an output file that averages about 60% of the size of the input text file. The command line syntax for the help compiler is: HC <inputfile> <outputfile> Although you can name the files anything you like, we recommend giving the input file a .TXT extension, and the output file a .HLP extension. Make certain that you never place the input file in the <outputfile> field or else your input file could be overwritten. At this point, you have your application's help file and are ready to program your application to use it. The first function to call is helpopen. This function takes the name of the help file, and the colors used to display the help window and help- related messages. Note that helpopen doesn't actually open any files; it just activates the help system so that helprun can be called. helprun takes a string pointer as an argument. The string 12 PICTOR User's Guide and Reference should match one of the topic names in your help file. If NULL is passed to helpopen, a help index list box is displayed and the user can select from any of the topics contained in the help file. You can use the helpsetcontext and helpgetcontext macros to set and retrieve the current help context. Although the help context has no effect on calls made by your application directly to helprun, some PICTOR library routines that take input from the user will call the help system if the user presses <F1> and the help system has been enabled (by calling helpopen). The help topic string that is passed to helprun by these functions is the string specified by the help context. Note that help text is uncompressed "on-the-fly" only for the topics viewed by the user. The first time helprun is called, several data structures are built. This means that if your application only calls helpopen and the user never activates your application's help system (that is, helprun is never called), no overhead associated with opening the help file or allocating memory for the data structures is incurred. You can call helpclose to destroy the data objects created by helprun if you need to recover the memory for them before your program terminates. For more information on the help functions, and to see an example application, refer to the helprun description in the function reference section. For a more significant help example, refer to the help included with the text editor sample application that is included in this package. Serial Communications The PICTOR library provides support for RS-232 asynchronous serial communications. The communications routines implement interrupt-driven data input (data output is not interrupt- driven). Note that this version of the library only supports one serial port at one time. Although there are MS-DOS and ROM BIOS services available for serial communications, none of them are interrupt driven. To use these services, your program must either continually poll the receive status, or risk losing data while your program is performing another task. In addition, these services don't support the highest baud rates possible on PC's. For these reasons, the PICTOR communications routines by-pass the MS-DOS and ROM-BIOS services altogether and program the hardware directly. The comopen function is used to prepare the serial port for input and output. All other communications functions return an error if comopen has not been called. Specifically, comopen does the following: 13 PICTOR User's Guide and Reference * Configures the serial port according to the port number, baud rate, parity, data bits, stop bits, and IRQ (interrupt request) values that you supply. * Installs an interrupt handler for receiving data. The handler places the data received in an internal circular buffer where it remains until one of the communications functions is called to retrieve it. * Installs an interrupt handler for the system timer. This handler is used for detecting time-out conditions. The other communications routines are: Function Description ----------------------------------------------------- comclose Uninstalls the interrupt handlers installed by comopen. comflush Clears any characters waiting in the receive buffer. comgetc Reads a single character from the serial port. comgets Reads a '\r'-terminated string from the serial port. comloc Returns the number of characters waiting in the receive buffer. computc Writes a character to the serial port. computs Writes a null-terminated string to the serial port. comread Reads the specified number of characters from the serial port. comwrite Writes the specified number of characters to the serial port. In addition, the comsettimeout and comgettimeout macros can be used to set and retrieve the time-out value. The time-out value specifies the amount of time allowed between characters before a time-out condition is generated. See the function reference section for a detailed description of each of the communications functions. Additional Information This section has described how to use some of the key features of the PICTOR library. We recommend that you browse through the function reference section if you haven't done so already. Reading the function descriptions will give you an idea of the features available in this package. In addition, many function descriptions include example programs. These example programs are also on the distribution disk(s) for you to compile and modify. The distribution disk(s) also includes Ed, a text editor program. All the source code is included. Ed makes use of many of the features of the PICTOR library. In addition, you can review the 14 PICTOR User's Guide and Reference source code to see an implementation of a text editor and, perhaps, customize it to suit your needs. Ed is missing many features that would be required of a commercial text editor program, but it has a strong foundation from which a more professional text editor could be built. Refer to the file README.DOC for additional information about working with the editor source code. Technical Assistance As a free program, we cannot provide technical support for this product. However, you may write to us at the address below if you have any comments or questions. We will try to respond to all correspondence. If you would like a printed manual, with table of contents and index, for the Pictor library, send $9.00 + $1.50 shipping to: SoftCircuits Programming P.O. Box 16262 Irvine, CA 92713 FUNCTIONS ---------------------------------------------------------------- This section provides a complete reference for all of the PICTOR library functions and macros in alphabetical order. There are several items that describe each function. The meaning of each item is as follows: Item Meaning ------------------------------------------------------------- Syntax Shows the data types received and returned by the function or macro. Include Shows the include file that contains the prototype for the function or the definition for the macro. The include file also defines any constants or structures that are associated with the function. Description Gives a description of the function or macro. Returns Describes the return value, if any. See also Lists other functions or macros that are similar to, or are usually used with, the function. Example Some function descriptions give an example program that shows how to use the function. Example programs are complete programs that can be compiled and run. All example programs are on the distribution disk(s). Note that all the example programs place angle brackets (< >) around included header files. This assumes that you placed the included header files in your compiler's include directory. beep --------------------------------------------- 15 PICTOR User's Guide and Reference Syntax void beep(void); Include pictor.h Description This function sounds the computer's internal speaker. beep provides a standard way to alert the user by making a sound with the same frequency and duration as is produced by many PICTOR library routines (such as messagebox and editbox). Using the beep function to alert the user has an additional advantage because error beeps can then be disabled globally using seterrorbeep. Note that the beep function flushes the keyboard buffer to prevent keyboard overrun. See also seterrorbeep, tone center --------------------------------------------- Syntax int center(int inside, int outside); Include pictor.h Description This macro calculates the starting position so that an item with inside length is centered inside an item with outside length. The lengths can refer to either width or height. If inside is larger than outside, the result is undefined. Returns The centered starting position as described above. Example /* ** CENTER.C: Displays a message centered on the screen. */ #include <string.h> #include <pictor.h> char *msg = "Hello, from the PICTOR library!"; void main() { VIDEOSTRUCT vstruct; /* initialize library */ initvideo(); getvconfig(&vstruct); vcolor(foreback(BOLD+WHITE,BLUE)); cls(); 16 PICTOR User's Guide and Reference setvpos(center(1,vstruct.rows), center(strlen(msg),vstruct.columns)); vputs(msg); kbdread(); /* restore screen */ vcolor(foreback(WHITE,BLACK)); cls(); } cleareol --------------------------------------------- Syntax void cleareol(void); Include pictor.h Description The cleareol function clears from the current logical cursor position to the end of the line. The logical cursor position is updated to point to the start of the next line. See also wcleareol clrstatus --------------------------------------------- Syntax void clrstatus(void); Include pictor.h Description The clrstatus function clears the status bar. See also initstatus, statusbar cls --------------------------------------------- Syntax void cls(void); Include pictor.h Description This function clears the entire screen and positions both the logical and the hardware text cursor at the top, left corner of the screen. comclose --------------------------------------------- Syntax int comclose(void) Include comlib.h Description This function closes the communications port that was previously opened using comopen. Since comopen 17 PICTOR User's Guide and Reference registers comclose with the ANSI C library routine atexit, you do not need to call this function. atexit will call comclose upon normal program termination. You may want to call comclose to close the communications port before your program terminates or to reopen the communications port with a different configuration. There is no ill- effect from calling comclose multiple times. Returns 0 if successful or -1 if an error occurred. See also comopen comflush --------------------------------------------- Syntax int comflush(void); Include comlib.h Description Clears any characters waiting in the receive buffer for the communications port previously opened using comopen. Returns The number of characters that were in the buffer before it was flushed. See also comloc, comopen comgetc --------------------------------------------- Syntax int comgetc(char *cptr); Include comlib.h Description Gets the next available byte from the communication port previously opened using comopen. The byte is written to the character pointed to by cptr. Returns 0 if successful or -1 if an error occurred. See also comloc, comopen, computc, comsettimeout comgets --------------------------------------------- Syntax int comgets(char *buffer, int maxlen); Include comlib.h Description Reads a string from the communications port previously opened using comopen. Characters are 18 PICTOR User's Guide and Reference read from the serial port and copied to buffer until a carriage return ('\r') is copied or until maxlen characters have been copied. A null- terminator ('\0') is then appended to buffer. buffer should be big enough to hold maxlen + 1 characters. If you need to receive data that may include embedded carriage returns ('\r'), see the comread function. If an error occurs, buffer contains a null- terminated string with the characters that had been received prior to the error. Returns 0 if successful or -1 if an error occurred. See also comloc, comopen, computs, comread, comsettimeout comloc --------------------------------------------- Syntax int comloc(void); Include comlib.h Description The comloc function returns the number of characters waiting in the receive buffer for the communications port previously opened using comopen. Returns The number of characters waiting in the receive buffer. See also comflush, comopen comopen --------------------------------------------- Syntax int comopen(int comport, int baudrate, int parity, int databits, int stopbits, int irq); Include comlib.h Description Configures the specified communications port based on the given arguments. The constants (defined in PICTOR.H) allowed for each argument field are described below: Field Constant Meaning --------------------------------------------- comport CO_COM1 COM1 CO_COM2 COM2 CO_COM3 COM3 CO_COM4 COM4 baudrate CO_BAUD300 300 baud 19 PICTOR User's Guide and Reference CO_BAUD1200 1200 baud CO_BAUD2400 2400 baud CO_BAUD4800 4800 baud CO_BAUD9600 9600 baud CO_BAUD19200 19200 baud CO_BAUD38400 38400 baud CO_BAUD57600 57600 baud CO_BAUD115200 115200 baud parity CO_NOPARITY No parity CO_ODDPARITY Odd parity CO_EVENPARITY Even parity databits CO_DATA7 7 data bits CO_DATA8 8 data bits stopbits CO_STOP1 1 stop bit CO_STOP2 2 stop bits irq CO_IRQDEFAULT Standard IRQ4 for COM 1 and 3, IRQ3 for COM 2 and 4. CO_IRQ2 IRQ2 CO_IRQ3 IRQ3 CO_IRQ4 IRQ4 CO_IRQ5 IRQ5 The I/O address for the specified RS-232 adapter is read from the ROM BIOS data area. If the value read is 0, the specified communications port is considered invalid and comopen returns an error. When comopen is called for the first time, it registers comclose with the ANSI C library function atexit. atexit will automatically call comclose upon normal program termination. Note: The comopen function traps interrupt 0x1C. installclock also traps interrupt 0x1C. If you are using both functions and you need to manually remove or close either one, they must be uninstalled in the reverse order that they were installed. Returns 0 if successful or -1 if an error occurred. See also comclose, comsettimeout compress --------------------------------------------- Syntax WORD compress(BYTE *inbuff, WORD len, BYTE *outbuff, NODE *rootnode); Include compress.h Description Compresses an array of characters using the huffman compression algorithm. inbuff is a pointer 20 PICTOR User's Guide and Reference to a buffer with the characters to be compressed. len is the number of characters in inbuff. outbuff is where the compressed data will be written. rootnode is the root node to a compression code tree created with gettree. The huffman compression algorithm takes advantage of the fact that some characters are used more frequently than others. The more frequently a character is used, the fewer the number of bits that are used to represent that character. Therefore, compress is most effective when compressing straight text files and is not recommended for compressing binary data. Note that although this compression algorithm offers significant compression, if your file is compressed in multiple segments, it is possible for the compressed data to be larger than the original data in one or more of those segments. For this reason, outbuff should be larger than len bytes under most conditions. Also note that all characters in inbuff must have been included in the file stream passed to gettree when the code tree was created or compress will fail. Returns The number of bytes written to outbuff (the compressed length). See also freetree, gettree, readtree, uncompress, writetree Example /* ** COMPRESS.C: Compresses a text file. Use UNCOMP.C to ** restore to original form. */ #include <stdio.h> #include <string.h> #include <compress.h> BYTE inbuff[BUFSIZ]; BYTE outbuff[BUFSIZ + 200]; void main(int argc,char *argv[]) { FILE *istream,*ostream; WORD complen,uncomplen; NODE *rootnode; /* check arguments */ if(argc != 3 || !stricmp(argv[1],argv[2])) { printf("Usage:\tCOMPRESS <infile> <outfile>\n"); 21 PICTOR User's Guide and Reference return; } /* open files */ istream = fopen(argv[1],"rt"); ostream = fopen(argv[2],"wb"); if(istream == NULL || ostream == NULL) { printf("File error\n"); return; } /* build compression code tree */ rootnode = gettree(istream); if(rootnode == NULL) { printf("Out of memory\n"); return; } /* set file pointer back to beginning of file */ rewind(istream); /* write compressed code tree to file */ complen = writetree(rootnode,outbuff); putw(complen,ostream); fwrite(outbuff,sizeof(BYTE),complen,ostream); /* compress data and write to output file */ do { uncomplen = fread(inbuff,sizeof(BYTE),BUFSIZ, istream); complen = compress(inbuff,uncomplen,outbuff, rootnode); putw(uncomplen,ostream); putw(complen,ostream); fwrite(outbuff,sizeof(BYTE),complen,ostream); } while(uncomplen == BUFSIZ); /* indicate end of file */ putw(0x00,ostream); fclose(istream); fclose(ostream); } computc --------------------------------------------- Syntax int computc(char c); Include comlib.h Description Writes a single character to the communications port previously opened using comopen. 22 PICTOR User's Guide and Reference Returns 0 if successful or -1 if an error occurred. See also comgetc, comopen, comsettimeout computs --------------------------------------------- Syntax int computs(char *string); Include comlib.h Description Writes a null-terminated string to the communications port previously opened using comopen. The null-terminator is not written. If you need to send data that contains embedded null characters ('\0'), use the comwrite function. Returns 0 of successful or -1 if an error occurred. See also comgets, comopen, comsettimeout, comwrite comread --------------------------------------------- Syntax int comread(char *buffer, int count); Include comlib.h Description Copies count bytes to buffer from the communications port previously opened using comopen. Returns 0 if successful or -1 if an error occurred. See also comloc, comopen, comwrite, comsettimeout comgettimeout, comsettimeout --------------------------------------------- Syntax int comgettimeout(void); void comsettimeout(int timeout); Include comlib.h Description These macros get and set the time-out value used by the serial communications functions. Many of these functions return an error condition if a time-out occurs while trying to send or receive a character across the serial port. The time-out value defines the number of 18ths of a second allowed between each character transmitted or received before a time-out condition is generated. 23 PICTOR User's Guide and Reference Returns comgettimeout returns the current time-out value. comwrite --------------------------------------------- Syntax int comwrite(char *buffer, int count); Include comlib.h Description Copies count bytes from buffer to the communications port previously opened using comopen. Returns 0 if successful or -1 if an error occurred. See also comopen, comread, comsettimeout _CURR_WPANE --------------------------------------------- Include pictor.h Description The _CURR_WPANE macro is equal to the active window pane. You can use the macro as a structure; it is not a pointer. The effects of this macro are undefined if there is no active window pane. This macro is designed to only be used internally by PICTOR library functions but is documented here in case you need it. editbox --------------------------------------------- Syntax int editbox(char *prompt, char *buffer, int maxlen, char *title, COLORSTRUCT *colors); Include pictor.h Description The editbox function creates a window with the given prompt, and calls kbdedit to edit a string. buffer is where the edited text will be stored and maxlen is the maximum number of characters allowed. title is the title given to the window (use NULL for no title). colors is a pointer to a COLORSTRUCT structure that contains the colors used to display the window. Returns TRUE if the user pressed <Enter>, or FALSE if the user pressed <Escape>. If the user pressed <Escape>, the contents of buffer are not modified. 24 PICTOR User's Guide and Reference escpressed --------------------------------------------- Syntax int escpressed(void); Include pictor.h Description The escpressed macro determines if the last key returned by kbdread was the <Escape> key. This macro is useful with some library functions such as messagebox for determining if the function ended in response to the user pressing <Escape>. Returns TRUE if the last keystroke returned by kbdread was the <Escape> key, FALSE otherwise. foreback --------------------------------------------- Syntax int foreback(int foreground, int background); Include pictor.h Description The foreback macro combines foreground and background into a single color attribute value. Since PICTOR library functions that take color arguments require a single color integer, foreback can be used as an argument to those functions. Returns The combined color attribute as described above. See also vcolor Example For an example of foreback, please see the helprun example. frame --------------------------------------------- Syntax void frame(int top, int left, int height, int width); Include pictor.h Description This function draws a box using the current frame type. See also setframe freetree --------------------------------------------- Syntax void freetree(NODE *rootnode); 25 PICTOR User's Guide and Reference Include compress.h Description This function frees the memory for a compression code tree created with gettree or readtree. rootnode is a pointer to the tree's root node. This function is provided because simply passing a root node to the free function does not release all of the memory in the tree. See also compress, gettree, readtree, uncompress, writetree getaltkey --------------------------------------------- Syntax int getaltkey(int c); Include pictor.h Description Converts the ASCII character c into its Alt-key equivalent. For example, if c is 'A' or 'a', getaltkey returns the key code for ALT_A which is defined in PICTOR.H. Returns The Alt-key equivalent of c, or 0 if c is not alpha-numeric. See also gethotkey getcurs, getcurscol, getcursrow --------------------------------------------- Syntax int getcurs(void); int getcurscol(void); int getcursrow(void); Include pictor.h Description The getcurs routines return the current location of the hardware text cursor. getcurs returns the location as a single integer value. The high byte contains the cursor's row coordinate; the low byte contains the cursor's column coordinate. The getcursrow and getcurscol macros return the row and column coordinates separately. Returns The cursor location as described above. See also getvcol, getvrow, setcurs getcurstype --------------------------------------------- Syntax int getcurstype(void); 26 PICTOR User's Guide and Reference Include pictor.h Description This function returns the starting and ending scan lines of the current hardware text cursor. The high byte of the return value contains the cursor's starting scan line, and the low byte contains the ending scan line. Returns The current cursor type as described above. See also setcurstype gethotkey --------------------------------------------- Syntax int gethotkey(char *string); Include pictor.h Description This function returns the first character in string that would be printed bold by hputs. This is the character that follows the first tilde (~) character. Returns The first character in string following the first tilde character or 0 if string contains no such character. See also getaltkey, hputs getscrn --------------------------------------------- Syntax void getscrn(int *buffer, int top, int left, int height, int width); Include pictor.h Description Copies the data from the region of the screen specified by the last 4 arguments to buffer. getscrn is used to save the screen before opening a window. The window can then be closed by using putscrn to write the original data back to the screen. Since getscrn is called automatically by wopen, you'll only need to call this function if you are writing custom windowing routines. The size of buffer should be ((height * width) * sizeof(int)). See also putscrn gettree 27 PICTOR User's Guide and Reference --------------------------------------------- Syntax NODE *gettree(FILE *stream); Include compress.h Description Builds a compression code tree for the characters in stream and returns a pointer to the root node. Since the compression routines are unable to process blocks of data larger than 64k, and the code tree must include all of the characters to be compressed, this function takes a FILE pointer as its argument (as opposed to a buffer pointer). Characters are read from stream starting from the current file position and continuing until the end of file, or until an error occurs. Note that stream remains open and the file position associated with stream points past the last character read when gettree returns. Returns A pointer to the root node or NULL if there was not enough memory to create the tree. See also compress, freetree, readtree, uncompress, writetree Example For an example of gettree, please see the compress example. getvcol, getvrow --------------------------------------------- Syntax int getvcol(void) int getvrow(void) Include pictor.h Description These two macros return the current logical screen position used by PICTOR library routines. Returns The current logical screen position as described above. See also getcurs, getwcol, getwrow, setvpos getvconfig --------------------------------------------- Syntax void getvconfig(VIDEOSTRUCT *vstruct); Include pictor.h Description This function fills vstruct with information that reflects the display configuration at the time of the last call to initvideo. initvideo must have 28 PICTOR User's Guide and Reference been previously called in order for getvconfig to return meaningful values. The VIDEOSTRUCT structure contains the following members: Member Description -------------------------------------------------- unsigned segment The display segment address. Will be one of the constants COLOR_SEG or MONO_SEG, which are defined in PICTOR.H. int snowcheck TRUE if snow checking is enabled, FALSE otherwise. (See the snowcheckoff macro for a description of snow checking.) int rows The number of text rows on the display. int columns The number of text columns on the display. int mode The video mode. int page The active video page. int colorsupport TRUE if the display adapter supports color, FALSE otherwise. Note that some systems may have a color adapter with a non-color display (such as composite monitors and some LCD's). For this reason, many applications allow the user to specify that only black and white attributes be used. See also initvideo Example For an example of getvconfig, please see the xprintf example. getwcol, getwrow --------------------------------------------- Syntax int getwcol(void); int getwrow(void); Include pictor.h Description The getwcol and getwrow functions return the current column and row position of the active window pane. Returns The current position of the active window pane as described above. If there is no active window pane, both functions return 1. 29 PICTOR User's Guide and Reference See also getvcol, getvrow, setwpos getwcols, getwrows --------------------------------------------- Syntax int getwcols(void); int getwrows(void); Include pictor.h Description The getwcols and getwrows macros return the number of columns and rows in the active window pane. The values returned are the number of columns or rows inside the window pane not counting the window frame or pane border. Returns The number of columns or rows in the active window pane. The return values are undefined if there is no active window pane. See also getwcol, getwrow helpclose --------------------------------------------- Syntax void helpclose(void); Include pictor.h Description This function destroys all data objects associated with the current help file, frees the memory used for those data objects and disables the help system. Since MS-DOS automatically reclaims any memory allocated by your application when the application terminates, you do not need to call this function. However, you can call this function if you need to recover memory allocated by the help system before your application terminates. See also helpopen, helprun helpopen --------------------------------------------- Syntax void helpopen(char *filename, COLORSTRUCT *hlpcolors, COLORSTRUCT *msgcolors); Include pictor.h Description This function specifies the filename and color attributes to be used by the help system when helprun is called. In effect, helpopen activates the help system. filename specifies the name of 30 PICTOR User's Guide and Reference the help file. The help file must be compatible with the format created by the help compiler included with the PICTOR tool kit. hlpcolors points to a COLORSTRUCT structure that contains the colors to be used to display the help screen. msgcolors points to a COLORSTRUCT structure that contains the colors to be used to display the help index and any help messages that must be displayed. If helpopen is called after help has already been enabled, helpopen begins by calling helpclose to destroy any data objects associated with the previous help file. It should be pointed out that helpopen doesn't actually open any files. The help file is not accessed until helprun is called and helprun never lets any files remain open between calls. See also helpclose, helprun Example For an example of helpopen, please see the helprun example. helpgetcontext, helpsetcontext --------------------------------------------- Syntax char *helpgetcontext(void); void helpsetcontext(char *context); Include pictor.h Description The helpgetcontext and helpsetcontext macros get and set the current help context. These functions aid in the development of applications with context-sensitive help. Many PICTOR library routines that get input from the user (such as messagebox and editbox) call helprun if the user presses <F1> (assuming that the help system has been enabled using helpopen). The help context is a pointer to a help topic string that gets passed to helprun by these functions. Note that the help context does not affect calls made directly to helprun by your application. Returns helpgetcontext returns a pointer to the current help context string. See also helpopen, helprun helprun 31 PICTOR User's Guide and Reference --------------------------------------------- Syntax int helprun(char *topic); Include pictor.h Description Runs the help system. topic is a pointer to a help topic string and should match a @BEGIN label defined in the help file. If topic is NULL, the help index is displayed and the user can select from any topic in the help file. Note that you must call helpopen to activate the help system prior to calling helprun. See the tutorial section for a discussion about creating on-line help. Note that since messagebox and listbox can be called from helprun, and helprun can be called from messagebox and listbox, helprun simply calls beep if helprun gets called recursively (gets called when it is already active). Returns TRUE if help was successful, FALSE if an error occurred. Note that if an error occurred, helprun displays a message to notify the user of the nature of the error. See also helpclose, helpopen, helpsetcontext Example /* ** HELPRUN.C: Help file viewer. */ #include <stdio.h> #include <pictor.h> COLORSTRUCT helpcolors = { foreback(BLACK,WHITE), foreback(BOLD|WHITE,WHITE), foreback(WHITE,BLACK), foreback(BLACK,BLACK) }; COLORSTRUCT msgcolors = { foreback(BLACK,CYAN), foreback(BOLD|WHITE,CYAN), foreback(WHITE,BLACK), foreback(BOLD|WHITE,BLACK) }; void main(int argc,char *argv[]) { /* check command-line arguments */ if(argc != 2) { 32 PICTOR User's Guide and Reference printf("Usage:\tHELPRUN <hlpfile>\n"); return; } /* initialize library */ initvideo(); cls(); initstatus(25,helpcolors.normal); /* capture Ctrl-Break & critical error interrupts */ hookints(&msgcolors); /* activate help system */ helpopen(argv[1],&helpcolors,&msgcolors); /* run help starting with help index */ helprun(NULL); /* restore screen */ vcolor(foreback(WHITE,BLACK)); cls(); } hookints --------------------------------------------- Syntax int hookints(COLORSTRUCT *colors); Include pictor.h Description This function installs interrupt handlers for Ctrl-C, Ctrl-Break and critical errors (interrupts 0x23, 0x1B and 0x24). The handlers for Ctrl-C and Ctrl-Break simply return. The handler for critical errors calls messagebox to display an error message with the MB_RETRYABORT flag. colors points to a COLORSTRUCT structure that contains the colors that will be passed to messagebox during critical errors. hookints makes your application more robust by preventing premature termination due to the user pressing <Ctrl-Break>, or aborting a critical error. In addition, the critical error handler prevents the default MS-DOS critical error handler from writing to the display, and errors can be handled in a consistent, user-friendly way. hookints registers unhookints with the ANSI C library function atexit. This causes unhookints to be called (and the installed handlers to be uninstalled) upon normal program termination. 33 PICTOR User's Guide and Reference Returns 0 if the function is successful or -1 if an error occurred. See also unhookints Example For an example of hookints, please see the helprun example. hputs --------------------------------------------- Syntax void hputs(char *string, int hcolor); Include pictor.h Description The hputs function prints a string that contains highlighted characters. This function is useful for printing menu selections with embedded "hotkeys", and is used by several PICTOR library functions such as runmenu and messagebox. hputs prints string using the current default colors. Any characters that are preceded by a tilde character (~) are printed using hcolor. The tilde character is not printed. See also gethotkey, hstrlen Example /* ** HPUTS.C: Writes a string using hputs. */ #include <pictor.h> void main() { /* initialize library */ initvideo(); setvpos(5,10); vcolor(foreback(BOLD+CYAN,BLUE)); cls(); hputs("~Retry, ~Abort, ~Fail, ~F~1=Help", foreback(BOLD+WHITE,BLUE)); } hstrlen --------------------------------------------- Syntax int hstrlen(char *string); 34 PICTOR User's Guide and Reference Include pictor.h Description This function returns the length of a string as printed by hputs. This is the number of characters in string, not counting the tilde character (~). Returns The number of characters in string that would be displayed by hputs. See also hputs initstatus --------------------------------------------- Syntax void initstatus(int row, int color); Include pictor.h Description This function specifies parameters used by the statusbar function to display the status bar. row specifies the status row and color specifies the status bar color. By default, the status bar appears on row 25 with a color attribute equal to foreback(BLACK, WHITE). See also statusbar initvideo --------------------------------------------- Syntax void initvideo(void); Include pictor.h Description initvideo determines the type and configuration of the host display adapter, and initializes internal variables appropriately. This function should be called at the start of your program. IMPORTANT: Many PICTOR library routines require that initvideo has already been called in order for those routines to work correctly. Use getvconfig to retrieve information about the current display configuration. See also getvconfig, snowcheckoff installclock --------------------------------------------- Syntax int installclock(int row, int column, int color); Include pictor.h 35 PICTOR User's Guide and Reference Description This function puts a clock on the screen at the location specified by row and column using the color attribute specified by color. The clock is automatically updated to display the current time. When installclock is called for the first time, it registers removeclock with the ANSI C library function atexit. This causes removeclock to be called upon normal program termination. Note that when your program terminates, it is possible for the clock to display itself between the time your program clears the screen and the time removeclock is called by atexit. In this situation, you might want to call removeclock explicitly before your program clears the screen. Returns 0 if successful or -1 if an error occurred. See also removeclock Example /* ** INSTCLCK.C: Installs an on-screen clock. */ #include <pictor.h> void main() { /* initialize library */ initvideo(); cls(); installclock(1,1,foreback(BLACK,WHITE)); setvpos(5,5); vputs("Press any key to move clock"); kbdread(); removeclock(); cls(); installclock(1,74,foreback(BLACK,WHITE)); setvpos(5,5); vputs("Press any key to exit"); kbdread(); } kbdedit --------------------------------------------- Syntax int kbdedit(char *buffer, int row, int column, int width,int maxlength, 36 PICTOR User's Guide and Reference COLORSTRUCT *colors); Include pictor.h Description This function allows the user to edit a line of text. buffer is where the text will be stored. row and column specify the screen location. width specifies how many display columns kbdedit will use for editing. maxlength specifies the maximum number of characters the string can contain. If maxlength is greater than width, the text is scrolled horizontally as the string grows longer than the edit area. buffer must be big enough to hold maxlength + 1 characters. If buffer already contains a string, kbdedit highlights the existing text to indicate that it is selected. If the user types an editing key (such as <Backspace>, <Left>, or <End>), the selected text becomes unselected and the user can modify the existing string. Otherwise, if the user begins typing a new string, it automatically replaces the selected text. kbdedit uses an internal buffer of 129 bytes. buffer should never contain a string of more than 128 characters or the internal buffer will overflow. If maxlength is greater than 128, kbdedit uses 128 as the maximum length. See also kbdread, editbox Returns TRUE if the user pressed <Enter>, or FALSE if the user pressed <Escape>. If the user pressed <Escape>, the original contents of buffer are not modified. Example /* ** KBDEDIT.C: Lets the user edit a string ** using kbdedit. */ #include <stdio.h> #include <pictor.h> COLORSTRUCT colors = { foreback(BLACK,WHITE), 0x00, /* not used by kbdedit() */ foreback(WHITE,BLACK), 0x00 /* not used by kbdedit() */ }; 37 PICTOR User's Guide and Reference char buffer[128]; void main() { int i; /* initialize library */ initvideo(); /* clear screen */ vcolor(foreback(BOLD+WHITE,BLUE)); cls(); setvpos(3,5); vputs("KbdEdit: ["); setvpos(3,15 + 25); vputc(']'); i = kbdedit(buffer,3,15,25,127,&colors); /* restore screen */ vcolor(foreback(WHITE,BLACK)); cls(); /* print result */ if(i == TRUE) printf("You entered: %s\n",buffer); else printf("You pressed <Escape>\n"); } kbdflush --------------------------------------------- Syntax int kbdflush(void); Include pictor.h Description This function flushes any keystrokes waiting in the keyboard buffer or stuffed using kbdpush. Returns The number of keystrokes that were in the keyboard buffer before it was flushed. See also kbdread, kbdready kbdpush --------------------------------------------- Syntax void kbdpush(int key); Include pictor.h 38 PICTOR User's Guide and Reference Description Stuffs key into the keyboard buffer so that it is the next key returned by kbdread. Only one key can be stuffed at a time. If kbdpush is called twice with no intervening call to kbdread, the first key pushed will be lost. See also kbdread, kbdready kbdread --------------------------------------------- Syntax int kbdread(void) Include pictor.h Description This function retrieves the next available keystroke. The value returned indicates which key was pressed. The low byte is the key's ASCII code (or 0 if the key has no ASCII code) and the high byte is the key's scan code. The returned value is the same as the one returned by the ROM BIOS interrupt 16h, function 00h except for <Ctrl- Break>. kbdread returns 0xFFFF for <Ctrl-Break> while the ROM BIOS returns 0x0000. PICTOR.H defines constants for many keyboard codes. Returns The next available keystroke as described above. See also escpressed, kbdpush, kbdready, kbdshift kbdready --------------------------------------------- Syntax int kbdready(void) Include pictor.h Description This function indicates if there are any keystrokes waiting in the keyboard buffer. If there are keystrokes waiting, the next available keystroke (as returned by kbdread) is returned_but not removed_from the keyboard buffer. Otherwise, 0 is returned. Returns The next available keystroke as described above, or 0 if no keystrokes are available. See also kbdpush, kbdread kbdshift --------------------------------------------- 39 PICTOR User's Guide and Reference Syntax int kbdshift(void); Include pictor.h Description This function returns the state of various keyboard shift keys as follows: Bit Meaning (if set) --------------------------------------------- 0 Right shift key is down 1 Left shift key is down 2 Ctrl key is down 3 Alt key is down 4 Scroll lock is on 5 Num Lock is on 6 Caps Lock is on 7 Insert is on Returns The current shift status as described above. See also kbdread Example /* ** KBDSHIFT.C: Displays the state of the shift keys until ** the user presses <Escape>. */ #include <pictor.h> char *labels[] = { "Right shift key down", "Left shift key down", "Ctrl-key down", "Alt key down", "Scroll Lock on", "Num Lock on", "Caps Lock on", "Insert on", }; void main() { int i,shiftstate; /* initialize library */ initvideo(); /* clear screen and hide cursor */ cls(); showcurs(FALSE); 40 PICTOR User's Guide and Reference setvpos(10,1); vputs("Press <Escape> to end"); while(!kbdready() || kbdread() != ESCAPE_KEY) { shiftstate = kbdshift(); for(i = 0;i < 8;i++) { setvpos(1 + i,1); xprintf(vputs,"%s: %s",labels[i], (shiftstate & (0x01 << i)) ? "Yes" : "No "); } } /* restore screen */ showcurs(TRUE); cls(); } listbox --------------------------------------------- Syntax int listbox(char **items, int numitems, int *selection, char *title, COLORSTRUCT *colors); Include pictor.h Description This function allows the user to select from an array of items. items is the address of an array of string pointers; these strings are the items that will appear in the list box. numitems is the number of items in the array. selection points to an integer that contains the initial selection. If selection points to an integer with a value of 0, the first item in the list is highlighted when listbox opens. If the user pressed <Return>, the integer pointed to by selection is modified to indicate which item was selected; if the user pressed <Escape>, the integer pointed to by selection is not modified. title is the title given to the window (use NULL for no title) and colors is a pointer to a COLORSTRUCT structure that contains the colors used to display the window. Returns TRUE if the user pressed <Return>, FALSE if the user pressed <Escape> or if numitems is 0. You can use escpressed to determine if the user pressed <Escape>. See also escpressed, pickfile Example /* 41 PICTOR User's Guide and Reference ** LISTBOX.C: Lets the user select from a list ** of items. */ #include <stdio.h> #include <pictor.h> #define NUM_ITEMS 7 char *items[NUM_ITEMS] = { "Apples", "Bananas", "Carrots", "Grapes", "Kiwi", "Raisins", "Watermelon", }; COLORSTRUCT colors = { foreback(BOLD+CYAN,BLUE), foreback(BOLD+WHITE,CYAN), foreback(BLACK,WHITE), foreback(BOLD+WHITE,WHITE) }; void main() { char buffer[45]; int sel = 0; /* initialize the library */ initvideo(); if(listbox(items,NUM_ITEMS,&sel,"Fruit",&colors)) { sprintf(buffer,"You selected %s",items[sel]); messagebox(buffer,NULL,MB_OK,&colors); } else { messagebox("You pressed <Escape>",NULL,MB_OK, &colors); } } messagebox --------------------------------------------- Syntax int messagebox(char *message, char *title, int flags,COLORSTRUCT *colors); Include pictor.h Description messagebox displays a window with a message and allows the user to select from 1 or more predefined responses. message is the message 42 PICTOR User's Guide and Reference displayed in the window. message can contain new- line ('\n') characters for multi-line messages. title is the title given to the window (use NULL for no title). colors is a pointer to a COLORSTRUCT structure that contains the colors used to display the window. flags determines the responses made available to the user and can be any one of the following constants defined in PICTOR.H: Constant Meaning --------------------------------------------- MB_OK The user is given a single selection labeled OK. MB_OKCANCEL The user can select between OK and Cancel. MB_RETRYCANCEL The user can select between Retry and Cancel. MB_RETRYABORT The user can select between Retry and Abort. MB_YESNO The user can select between Yes and No. MB_YESNOCANCEL The user can select between Yes, No and Cancel. Returns If a single response is available as with MB_OK, messagebox always returns 0. If two responses are available as with MB_OKCANCEL, messagebox returns 1 if OK is selected and 0 if Cancel is selected. If three responses are available as with MB_YESNOCANCEL, messagebox returns 2 if Yes is selected, 1 if No is selected and 0 if Cancel is selected. Also, if the user presses <Escape>, messagebox returns 0. You can use the escpressed macro determine if 0 was returned because the right-most response was selected or <Escape> was pressed. See also escpressed Example /* ** MSGBOX.C: Takes action based on the user's response ** to a message box. */ #include <pictor.h> COLORSTRUCT msgcolors = { foreback(BOLD+WHITE,RED), foreback(BOLD+YELLOW,RED), foreback(BLACK,WHITE), foreback(BOLD+WHITE,WHITE) 43 PICTOR User's Guide and Reference }; void main() { /* initialize library */ initvideo(); /* clear screen if user selects yes */ if(messagebox("Do you want the screen cleared?", "Question",MB_YESNO,&msgcolors)) { vcolor(foreback(WHITE,BLACK)); cls(); } } multiedit --------------------------------------------- Syntax int multiedit(MEDITSTRUCT *items, int numitems, char *title, COLORSTRUCT *colors); Include pictor.h Description This function creates an edit box with multiple edit fields. The user can move between fields by pressing <Tab> and <Shift-Tab>. items points to the first element of an array of MEDITSTRUCT structures. The MEDITSTRUCT structures describe each field of the multi-edit box and contain the following members: Member Description --------------------------------------------- char *prompt Prompt message for this field char *buffer Buffer to store text int maxlen Maximum number of characters allowed in this field numitems is the number of MEDITSTRUCT structures in the array and, therefore, the number of fields in the edit box. title is the title given to the window (use NULL for no title). colors points to a COLORSTRUCT structure that contains the colors used to display the window. Returns TRUE if the user pressed <Enter>, FALSE if the user pressed <Escape>. Unlike kbdedit, some fields may have been modified when this function returns even if <Escape> was pressed. See also editbox, kbdedit 44 PICTOR User's Guide and Reference Example /* ** MULTEDIT.C: Uses multiedit to display a dialog ** box with multiple edit fields. */ #include <stdio.h> #include <pictor.h> #define MAX_LEN 25 char buff1[MAX_LEN + 1]; char buff2[MAX_LEN + 2]; #define NUM_ITEMS 2 MEDITSTRUCT items[NUM_ITEMS] = { { "Find What",buff1,MAX_LEN }, { "Replace with",buff2,MAX_LEN } }; COLORSTRUCT colors = { foreback(BLACK,WHITE), foreback(BOLD+WHITE,WHITE), foreback(WHITE,BLACK), foreback(BOLD+WHITE,BLACK) }; void main() { char buffer[81]; /* initialize library */ initvideo(); if(multiedit(items,NUM_ITEMS,"Replace",&colors)) { sprintf(buffer, "You entered:\n\"%s\"\nand:\n\"%s\"", buff1,buff2); messagebox(buffer,NULL,MB_OK,&colors); } else { messagebox("You pressed <Escape>",NULL,MB_OK, &colors); } } pause --------------------------------------------- Syntax void pause(int duration); Include pictor.h 45 PICTOR User's Guide and Reference Description pause returns after the specified period of time has elapsed. duration specifies the pause duration in approximately 18ths of a second (a duration of 18 is just under one second). pickfile --------------------------------------------- Syntax char *pickfile(char *filespec, char *title, COLORSTRUCT *colors); Include pictor.h Description This function uses listbox to let the user select from a sorted list of files. filespec masks which files to include in the selection. title specifies the window title passed to listbox (use NULL for no title). colors points to a COLORSTRUCT structure that contains the colors used to display the window. If the user selects a file, pickfile returns a pointer to the file name. You should make use of the pointer as soon as possible since another call to pickfile can change the data it points to. Returns A pointer to the selected filename or NULL if the user pressed <Escape>, or if an error occurred (in which case pickfile displays a message notifying the user). You can use the escpressed macro to determine if the user pressed <Escape>. See also escpressed, listbox Example /* ** PICKFILE.C: Lets the user select a file in the ** current directory. */ #include <stdio.h> #include <pictor.h> COLORSTRUCT colors = { foreback(BOLD+CYAN,BLUE), foreback(BOLD+WHITE,CYAN), foreback(BLACK,WHITE), foreback(BOLD+WHITE,WHITE) }; void main() { char buffer[45]; 46 PICTOR User's Guide and Reference char *cptr; /* initialize the library */ initvideo(); cptr = pickfile("*.*","Pick a File",&colors); if(cptr != NULL) { sprintf(buffer,"You selected %s",cptr); messagebox(buffer,NULL,MB_OK,&colors); } else { messagebox("You pressed <Escape>",NULL,MB_OK, &colors); } } popcurs, pushcurs --------------------------------------------- Syntax int popcurs(void); int pushcurs(void); Include pictor.h Description These functions work together to save and restore the cursor state. pushcurs saves the current hardware text cursor position and cursor type. popcurs restores the cursor position and type to what it was before the last call to pushcurs. Returns Both functions return TRUE if they are successful. pushcurs returns FALSE if there is no more room to save the cursor; popcurs returns FALSE if there is no saved cursor to pop. popstatus, pushstatus --------------------------------------------- Syntax int popstatus(void); int pushstatus(void); Include pictor.h Description These functions work together to save the status bar and then restore it. pushstatus save the contents of, and then clears, the status bar. popstatus restores the status bar to how it appeared prior to the last call to pushstatus. Returns Both function return TRUE if they are successful. pushstatus returns FALSE if there is no more room to save the status bar. popstatus returns FALSE if there is no saved status bar to pop. 47 PICTOR User's Guide and Reference prnputc --------------------------------------------- Syntax int prnputc(char c); Include pictor.h Description This function writes c to the standard list device (printer). Returns 0 if successful or a non-zero value if an error occurred. See also prnputs, prnwrite prnputs --------------------------------------------- Syntax int prnputs(char *string); Include pictor.h Description This function writes string to the standard list device (printer). Returns 0 if successful or a non-zero value if an error occurred. See also prnputc, prnwrite prnwrite --------------------------------------------- Syntax int prnwrite(char *buffer, int count); Include pictor.h Description This function writes a series of characters to the standard list device (printer). buffer is where the characters are stored and count is the number of characters to be written. Returns 0 if successful or a non-zero value if an error occurred. See also prnputc, prnputs putscrn --------------------------------------------- Syntax void putscrn(int *buffer, int top, int left, int height, int width); Include pictor.h 48 PICTOR User's Guide and Reference Description Copies the contents of buffer to the display area described by the last four arguments. putscrn is useful for closing a window by writing the original contents of the screen (saved with getscrn) back to the screen. Since wclose automatically calls this function to close a window, you won't need to call putscrn unless you are creating customized windowing routines. See also getscrn readtree --------------------------------------------- Syntax NODE *readtree(BYTE *buffer); Include compress.h Description Builds a compression code tree from a buffer created with writetree. Returns The root node to the compression code tree or NULL if there was not enough memory. See also compress, freetree, gettree, uncompress, writetree Example For an example of readtree, please see the uncompress example. removeclock --------------------------------------------- Syntax int removeclock(void); Include pictor.h Description Removes the on-screen clock previously installed by installclock. Note that installclock automatically registers removeclock with the ANSI C library routine atexit. This causes removeclock to be called upon normal program termination. As a result, you do not need to call removeclock. However, you might call this function if you want to stop the clock before your program terminates or if you want to re-install the clock at a different location. The installclock function traps interrupt 0x1C. comopen also traps interrupt 0x1C. If you are using both functions and you need to manually remove or close either one, they must be uninstalled in the reverse order that they were installed. 49 PICTOR User's Guide and Reference Returns 0 if successful or -1 if an error occurred. See also installclock Example For an example of removeclock, please see the installclock example. runmenu --------------------------------------------- Syntax int runmenu(MAINMENU *menu, COLORSTRUCT *maincolors, COLORSTRUCT *subcolors); Include pictor.h Description Runs the main menu specified by menu. maincolors and subcolors point to COLORSTRUCT structures that contain the colors used to display the mainmenu and submenus respectively. runmenu should be used in your program's main loop (see the example program below). If the next available keystroke is relevant to the current menu context, it is processed by runmenu and 0 is returned. Otherwise, the code for the keystroke is returned so that it can be processed by your program. See kbdread for a description of the keyboard codes. Returns The keyboard code if the last key pressed was not processed by the main menu, or 0 if it was. See also kbdread, showmenu Example /* ** RUNMENU.C: Demonstrates use of the PICTOR ** menu system. */ #include <stdio.h> #include <pictor.h> /* set mainloop = FALSE to terminate main loop */ int mainloop = TRUE; VIDEOSTRUCT vstruct; COLORSTRUCT menucolors = { foreback(BLACK,CYAN), foreback(BOLD+WHITE,CYAN), foreback(BOLD+CYAN,BLUE), 50 PICTOR User's Guide and Reference foreback(BOLD+WHITE,BLUE) }; /* give function references for menu tables */ void sample(void); void terminate(void); SUBMENU filemenu[] = { { "~New F2", "Create a new file",NULL,sample }, { "~Open...", "Open an existing file",NULL,sample }, { "~Save", "Save the current file",NULL,sample }, { "Save ~As", "Save the current file with a different name", NULL,sample }, SUBMENU_DIVIDER, { "E~xit","Exit to DOS",NULL,terminate }, END_SUBMENU }; SUBMENU editmenu[] = { { "~Cut Shift-Del", "Move text to clipboard",NULL,sample }, { "C~opy", "Copy text to clipboard",NULL,sample }, { "~Paste", "Paste text from clipboard",NULL,sample }, END_SUBMENU }; MAINMENU mainmenu[] = { { "~File","File operations menu",NULL,filemenu }, { "~Edit","Edit operations menu",NULL,editmenu }, END_MAINMENU }; void sample(void) { beep(); } void terminate(void) { mainloop = FALSE; } void main() { int i; /* initialize library */ initvideo(); 51 PICTOR User's Guide and Reference getvconfig(&vstruct); /* hide text cursor */ showcurs(FALSE); /* Default shadow color is white on black. Since */ /* our desktop is white on black, we need to make */ /* shadows darker in order for them to show up */ _PL_shadowcolor = foreback(BOLD+BLACK,BLACK); /* create desktop */ for(i = 2;i < vstruct.rows;i++) { setvpos(i,1); vrepc('\xB1',vstruct.columns); } showmenu(mainmenu,&menucolors,FALSE); initstatus(vstruct.rows,menucolors.normal); statusbar("<Alt>=Menus <F10>=Exit to DOS"); while(mainloop) { switch(runmenu(mainmenu,&menucolors,&menucolors)) { case 0: /* keystroke processed by runmenu */ break; case F2_KEY: sample(); break; case F10_KEY: mainloop = FALSE; break; default: beep(); break; } } /* restore screen */ vcolor(foreback(WHITE,BLACK)); showcurs(TRUE); cls(); } scroll --------------------------------------------- Syntax void scroll(int lines, int top, int left, int height, int width); Include pictor.h Description This function scrolls the area described by top, bottom, height, and width. lines specifies how far each row is scrolled. If lines is positive the area is scrolled up, if lines is negative the area 52 PICTOR User's Guide and Reference is scrolled down, and if lines is zero the specified area is cleared. See also cls, wclear setcurs --------------------------------------------- Syntax void setcurs(int row, int column); Include pictor.h Description This function sets the position of the hardware text cursor. Coordinates are 1-based so 1,1 refers to the top, left corner of the screen. Note that PICTOR routines use their own logical cursor and are not effected by the location of the hardware text cursor. See also popcurs, pushcurs, setvpos, synccurs, setwpos setcurstype --------------------------------------------- Syntax void setcurstype(int type); Include pictor.h Description Sets the starting and ending scan lines for the hardware text cursor. The upper byte of type specifies the starting scan line and the lower byte specifies the ending scan line. See also getcurstype, popcurs, pushcurs, showcurs seterrorbeep --------------------------------------------- Syntax void seterrorbeep(int state); Include pictor.h Description The seterrorbeep enables or disables the beep function. If state is FALSE, beep is disabled, if state is TRUE, beep is enabled. Many PICTOR library functions call beep to alert the user (usually because an invalid key was pressed). seterrorbeep effectively disables or enables error beeping for these functions. See also beep setframe, setdoubleframe, setsingleframe 53 PICTOR User's Guide and Reference --------------------------------------------- Syntax void setframe(char topbottom, char sides, char topleft, char topright, char bottomleft, char bottomright); void setdoubleframe(void) void setsingleframe(void); Include pictor.h Description The setframe routines describe the type of lines used by the frame function. The arguments to setframe specify the character to be used for each of the frame elements: topbottom (top and bottom), sides (left and right sides), topleft, topright, bottomleft, and bottomright (the corners of the frame). setdoubleframe and setsingleframe are simply macros that call setframe with arguments for a standard double-line frame and single-line frame respectively. Note that subsequent calls to frame will make use of the modified frame style, including internal library routines that call frame such as wopen and runmenu. See also frame setvpos --------------------------------------------- Syntax void setvpos(int row, int column); Include pictor.h Description setvpos sets the logical cursor position. PICTOR library routines use their own logical cursor position instead of the hardware text cursor. Use this function to set that position. row and column are 1-based; therefore, the top, left corner of the screen is at 1,1. See also getvcol, getvrow, setcurs, syncvpos, setwpos Example For an example of setvpos, please see the center example. setwpane --------------------------------------------- Syntax int setwpane(int handle); Include pictor.h 54 PICTOR User's Guide and Reference Description This functions sets the active window pane for the currently active window. handle is a handle that was returned by wpane when the window pane was created. Every window has at least one window pane. The original pane (the only pane if the window only has one) has a handle value of 0. Returns TRUE if the specified window pane is successfully selected, FALSE if handle is not a valid pane handle. Also see wpane Example For an example of setwpane, please see the wpane example. setwpos --------------------------------------------- Syntax void setwpos(int row, int column); Include pictor.h Description The setwpos function sets the logical window position for the active window pane. This determines the location of the next write using any of the window output functions. It also positions the hardware text cursor if the window was created with the WO_TEXTCURSOR attribute. Window pane coordinates are 1-based so 1,1 specifies the top, left corner of the window pane. See also setcurs, setvpos showcurs --------------------------------------------- Syntax void showcurs(int state); Include pictor.h Description Displays or hides the text cursor. The cursor is hidden if state is FALSE, restored if it is TRUE. This function modifies the cursor's starting and ending scan lines and may not work on every display. A more reliable way to hide the cursor may be to position it off the screen. For example, on a 25x80 display, use setcurs(26,1). See also setcurs, setcurstype showmenu --------------------------------------------- 55 PICTOR User's Guide and Reference Syntax void showmenu(MAINMENU *menu, COLORSTRUCT *colors, int highlight); Include pictor.h Description Displays the main menu specified by menu across the top of the screen. highlight specifies if the main menu hotkeys (those letters preceded by a tilde (~) character) are displayed using the bold attribute specified in the colors structure. If highlight is TRUE, the hotkeys are highlighted; otherwise, they aren't. See also runmenu Example For an example of showmenu, please see the runmenu example. snowcheckoff --------------------------------------------- Syntax void snowcheckoff(void); Include pictor.h Description Many older CGA displays will snow (flicker random white spots) when the screen is accessed too quickly. If initvideo determines that a CGA is the active adapter, it enables snow checking which slows down screen access in a manner that eliminates snow. Some newer CGA's do not snow, and some users of older CGA's may prefer snow to the slower performance resulting from snow checking. Therefore, the snowcheckoff macro is provided so that snow checking can be disabled. snowcheckoff has no effect if the current display adapter is not a CGA. statusbar --------------------------------------------- Syntax void statusbar(char *string); Include pictor.h Description Displays string on the status bar. See also clrstatus, initstatus synccurs --------------------------------------------- Syntax void synccurs(void); 56 PICTOR User's Guide and Reference Include pictor.h Description This function positions the hardware text cursor so that it matches the current logical cursor position. See also syncvpos syncvpos --------------------------------------------- Syntax void syncvpos(void); Include pictor.h Description This function positions the logical cursor so that it matches the hardware text cursor. See also synccurs tone --------------------------------------------- syntax void tone(int freq, int duration); Include pictor.h Description Sounds the computer's internal speaker. freq specifies the sound's frequency in cycles per second. duration specifies how long to play the tone. Each count of duration is equal to about an 18th of a second (a duration of 18 is just under 1 second). If you want to sound the computer's internal speaker to alert the user in a manner that is consistent with the way many of the internal library routines do, use the beep function which, in turn, calls tone. Using beep also allows your program to disable all warning beeps with a single call to seterrorbeep. See also beep Example /* ** TONE.C: Plays a series of tones. */ #include <pictor.h> void main() { 57 PICTOR User's Guide and Reference int i; for(i = 110;i <= 880;i += 20) tone(i,1); for( ;i >= 110;i -= 20) tone(i,1); } uncompress --------------------------------------------- Syntax void uncompress(BYTE *inbuff, WORD len, BYTE *outbuff, NODE *rootnode); Include compress.h Description Uncompresses data that was compressed using compress. inbuff is a pointer to a buffer with the compressed data. len specifies the length of the uncompressed (output) data. outbuff is where the uncompressed data will be written and must be big enough to hold len characters. rootnode points to the compression code tree used to compress the data. Note: rootnode must point to the same code tree used to compress the data or uncompress will fail. See also compress, freetree, gettree, readtree, writetree Example /* ** UNCOMP.C: Uncompresses a file that was compressed ** with COMPRESS.C. */ #include <stdio.h> #include <string.h> #include <compress.h> BYTE inbuff[BUFSIZ + 200]; BYTE outbuff[BUFSIZ]; void main(int argc,char *argv[]) { FILE *istream,*ostream; WORD complen,uncomplen; NODE *rootnode; /* check arguments */ if(argc != 3 || !stricmp(argv[1],argv[2])) { printf("Usage:\tUNCOMP <infile> <outfile>\n"); return; 58 PICTOR User's Guide and Reference } /* open files */ istream = fopen(argv[1],"rb"); ostream = fopen(argv[2],"wt"); if(istream == NULL || ostream == NULL) { printf("File error\n"); return; } /* read and uncompress code tree */ complen = getw(istream); fread(inbuff,sizeof(BYTE),complen,istream); rootnode = readtree(inbuff); if(rootnode == NULL) { printf("Out of memory\n"); return; } /* uncompress data and write to file */ while((uncomplen = getw(istream)) != 0) { complen = getw(istream); fread(inbuff,sizeof(BYTE),complen,istream); uncompress(inbuff,uncomplen,outbuff,rootnode); fwrite(outbuff,sizeof(BYTE),uncomplen,ostream); } fclose(istream); fclose(ostream); } unhookints --------------------------------------------- Syntax int unhookints(void); Include pictor.h Description This function uninstalls the Ctrl-C, Ctrl-Break and critical error handlers that were previously installed by hookints. Since hookints registers unhookints with the ANSI C library function atexit, you do not need to call this function. However, you can call it if you want to restore the handlers before your program terminates. There is no ill-effect from calling unhookints multiple times. Returns 0 if successful or -1 if an error occurred. See also hookints vcolor 59 PICTOR User's Guide and Reference --------------------------------------------- Syntax void vcolor(int color); Include pictor.h Description Selects the default colors for routines that write to the screen. Note that a number of library routines call this function and change the default colors so you should call vcolor just before writing to the screen. Use wcolor to change the default color for the current window pane. See also foreback, wcolor vgetca --------------------------------------------- Syntax int vgetca(void); Include pictor.h Description This function returns the character and attribute from the screen at the current logical cursor position. The low byte contains the character and the upper byte contains the attribute. Returns The character and attribute as described above. See also vputca vputa --------------------------------------------- Syntax void vputa(int color); Include pictor.h Description This function writes the color attribute color to the screen at the current logical position without disturbing the text at that location. See also vrepa vputc --------------------------------------------- Syntax void vputc(char c); Include pictor.h Description vputc writes the character c to the screen at the current logical cursor position using the current default colors. 60 PICTOR User's Guide and Reference See also setvpos, vcolor, wputc vputca --------------------------------------------- Syntax void vputca(int value); Include pictor.h Description This function writes a character and color attribute to the screen at the current logical cursor position. The low byte of value should contain the character and the high byte should contain the attribute. See also vgetca, vputc vputs --------------------------------------------- Syntax void vputs(char *string); Include pictor.h Description vputs writes a null-terminated string to the screen at the current logical cursor position. See also wputs, xprintf Example For an example of vputs, please see the center example. vrepa --------------------------------------------- Syntax void vrepa(int color, int count); Include pictor.h Description This function writes the color attribute specified by color for the number of columns specified by count without disturbing the text at that location. This function is useful for creating highlight bars. See also vputa, wrepa vrepc --------------------------------------------- Syntax void vrepc(char c, int count); Include pictor.h 61 PICTOR User's Guide and Reference Description This function writes c to the screen using vputc for the number of times specified by count. See also vputc, wrepc wclear --------------------------------------------- Syntax void wclear(void); Include pictor.h Description This function clears the contents of the active window pane and homes the window's logical cursor (and the hardware text cursor if the window was created with the WO_TEXTCURSOR attribute). wclear is always called by wopen when a new window or window pane is created. See also cls, scroll wcleareol --------------------------------------------- Syntax void wcleareol(void); Include pictor.h Description This function clears from the current window pane position to the end of the window pane. Unlike the cleareol function, wcleareol does not update the window pane's logical cursor position. See also cleareol, wclear wclose --------------------------------------------- Syntax void wclose(void); Include pictor.h Description This function closes the active window and frees memory associated with it. If another window was underneath the active window, that window then becomes the active window. See also wcloseall, wopen Example For an example of wclose, please see the wopen example. wcloseall 62 PICTOR User's Guide and Reference --------------------------------------------- Syntax void wcloseall(void); Include pictor.h Description This function closes all open windows and frees memory associated with them. See also wclose wcolor --------------------------------------------- Syntax void wcolor(int color); Include pictor.h Description This function changes the default color attribute for the active window pane to color. The window does not change appearance when this function is called. Instead, it sets the attribute to be used the next time the window pane is written to. See also foreback, vcolor wopen --------------------------------------------- Syntax int wopen(int top, int left, int height, int width, int color, int flags); Include pictor.h Description Creates and displays a new window. The first four arguments specify the location and size of the window. Note that since the window has a border, the window's display area is actually (height - 2) (width - 2). color specifies the window's color attribute. flags specifies optional window attributes. flags should be 0x00 if the window has no optional attributes, and multiple attributes can be combined using a bitwise OR (▌). flags can be any of the following constants defined in PICTOR.H: Constant Meaning --------------------------------------------- WO_SHADOW The window will be displayed with a shadow. WO_STATICMEM Causes wopen to allocate memory for the window from an internal static buffer instead of dynamically allocating memory using malloc. You should avoid using this flag since 63 PICTOR User's Guide and Reference the static buffer is relatively small. Also, windows that have the WO_STATICMEM attribute cannot have multiple panes. This flag is used by some of the library routines such as messagebox so that they can display errors when there is no more system memory, and so that they can be called from interrupt handlers (which should never call malloc). If the WO_STATICMEM attribute is specified and wopen cannot allocate enough memory from the static buffer for the window buffer, the screen beneath the window will not be saved and the window will still appear after it has been closed. If wopen cannot allocate enough static memory even for the window structure itself, wopen terminates the program by displaying an error message and calling exit. wopen never returns FALSE when WO_STATICMEM is specified. WO_TEXTCURSOR This gives the window a hardware text cursor. The cursor position is updated whenever the window pane's logical cursor position changes. WO_TEXTWRAP Normally, text that extends beyond the edge of the window is clipped (not displayed). If the WO_TEXTWRAP attribute is specified, characters that extend beyond the edge of the window wrap around to appear at the beginning of the next line. Returns TRUE if the window was successfully created and displayed, FALSE if there is not enough memory to create the window. See also wclose, wtitle Example /* ** WOPEN.C: Creates a window and displays some text in it. */ #include <pictor.h> void main() { /* initialize library */ 64 PICTOR User's Guide and Reference initvideo(); vcolor(foreback(BOLD+WHITE,BLUE)); cls(); /* create a window and write some text in it */ wopen(5,6,17,70,foreback(BLACK,WHITE),WO_SHADOW); wputs("Hello, world. wputs() here!\n\nPress any key"); /* wait for user to press a key */ kbdread(); wclose(); /* restore screen */ vcolor(foreback(WHITE,BLACK)); cls(); } wpane --------------------------------------------- Syntax int wpane(int direction, int position); Include pictor.h Description Splits the active window pane into two panes. direction specifies the direction of the split and can be any one of the following constants defined in PICTOR.H: Constant Meaning --------------------------------------------- WP_VERTICAL The current window pane is split vertically. WP_HORIZONTAL The current window pane is split horizontally. position is the column to split the window if direction is WP_VERTICAL, or the row to split the window if direction is WP_HORIZONTAL. When a window is created using wopen, it has a single pane that is as big as the window minus the window frame. The original pane always has a handle value of 0. wpane divides the current window pane into two panes and returns a handle to the new pane. The new pane is considered to be the pane on the right if direction is WP_VERTICAL, or the pane on the bottom if direction is WP_HORIZONTAL. The handle returned by this function can be passed to setwpane to make the new window pane active. If creating the new window pane would result in either the new window pane or the window pane being split having less than 3 rows or 3 columns 65 PICTOR User's Guide and Reference (1 row or column inside the pane's border), wpane refuses to create the new pane and an error is returned. Returns The handle to the new window pane as described above if successful, or 0 if an error occurred. See also setwpane Example /* ** WPANE.C: Divides a window into many panes. */ #include <pictor.h> void main() { int i,handle1,handle2; /* initialize library */ initvideo(); wopen(5,6,17,70,foreback(BOLD+CYAN,BLUE),0x00); handle1 = 0; handle2 = wpane(WP_VERTICAL,35); for(i = 0;i < 8;i++) { setwpane(handle1); xprintf(wputs,"Pane handle: %d",handle1); handle1 = wpane(WP_HORIZONTAL,3); setwpane(handle2); xprintf(wputs,"Pane handle: %d",handle2); handle2 = wpane(WP_HORIZONTAL,3); } kbdread(); wclose(); } wputc --------------------------------------------- Syntax void wputc(char c); Include pictor.h Description Writes c to the active window pane. c is written at the location of the active window pane's logical cursor position using the current window pane color. Characters extending beyond the edge of the window pane using wputc are clipped. 66 PICTOR User's Guide and Reference See also setwpos, vputc, wrepc wputs --------------------------------------------- Syntax void wputs(char *string); Include pictor.h Description Writes string to the active window pane. string is written starting at the location of the active window pane's logical cursor position using the current window pane color. Characters extending beyond the edge of the window pane are clipped. See also setwpos, vputs, xprintf Example For an example of wputs, please see the wopen example. wrepa --------------------------------------------- Syntax void wrepa(int color, int count); Include pictor.h Description Writes the color attribute specified by color to the active window pane and repeats it for the number of times specified by count. Printing begins at the window pane's logical cursor position. If count extends beyond the edge of the window pane, the output is clipped. See also vrepa, setwpos wrepc --------------------------------------------- Syntax void wrepc(char c, int count); Include pictor.h Description Writes c to the active window pane for the number of times specified by count. Printing begins at the window pane's logical cursor position. Characters extending beyond the edge of the window pane are clipped. See also vrepc, setwpos writetree 67 PICTOR User's Guide and Reference --------------------------------------------- Syntax WORD writetree(NODE *rootnode, BYTE *buffer); Include compress.h Description Writes the compression code tree specified by rootnode to buffer. The code tree is written so as to take the minimum number of bytes necessary. This function is suitable for writing a compression code tree to a buffer so that it can be written to a file. The data can later to converted back to a code tree using readtree. The required length of buffer varies depending on the number of characters included in the code tree. A typical value might be around 90 bytes. Since you don't know how many bytes will be required, you should be sure to use a buffer that is larger than the typical value. Returns The number of bytes that were written to buffer. See also compress, freetree, gettree, readtree, uncompress Example For an example of writetree, please see the compress example. wsynccurs --------------------------------------------- Syntax void wsynccurs(void); Include pictor.h Description This function synchronizes the hardware text cursor position with the current window pane's logical cursor position. The cursor is moved inside the window so that its location matches where text will be written with the next call to a window output function. If the current window pane's logical cursor position is not within the current window pane, the hardware text cursor is hidden. See also synccurs, syncvpos wtitle --------------------------------------------- Syntax void wtitle(char *string); Include pictor.h 68 PICTOR User's Guide and Reference Description Gives the active window pane a title by printing string centered across the top of the window pane. If string is NULL, the current title is cleared. xprintf --------------------------------------------- Syntax void xprintf(void (*func)(), char *format [, arguments ]...); Include pictor.h Description This function formats a string and sends it to any function that takes a single string as an argument. xprintf creates a formatted string using format and arguments and sends the result to func. The syntax is the same as for the ANSI C library function fprintf, but instead if the first argument specifying a stream, the first argument specifies a function. xprintf is designed to handle strings that fit on one line of the display. Creating lines that are longer than 132 characters will overflow the internal buffer. Example /* ** XPRINTF.C: Displays a window with information about ** the current display configuration. */ #include <pictor.h> void main() { VIDEOSTRUCT vstruct; /* initialize library */ initvideo(); getvconfig(&vstruct); /* create window and write information */ wopen(6,11,11,60,foreback(BOLD+WHITE,BLUE),0x00); xprintf(wputs,"Video segment: %04X\n", vstruct.segment); xprintf(wputs,"Snow checking: %s\n", (vstruct.snowcheck) ? "On" : "Off"); xprintf(wputs,"Text rows: %d\n",vstruct.rows); xprintf(wputs,"Text columns: %d\n",vstruct.columns); xprintf(wputs,"Video mode: %d\n",vstruct.mode); xprintf(wputs,"Display page: %d\n",vstruct.page); xprintf(wputs,"Color support: %s\n", 69 PICTOR User's Guide and Reference (vstruct.colorsupport) ? "Yes" : "No"); wputs("\nPress any key..."); /* wait for user to press a key and close window */ kbdread(); wclose(); } VARIABLES ------------------------------------------------------------- There are a number of variables that are used internally by the PICTOR library. Normally, these variables are set through function calls or through macros. We don't recommend directly accessing those variables that can be accessed through functions or macros. However, since the source code is provided with this package, these variables are documented here in case you need them. These variables all begin with _PL_ to indicate that they are PICTOR Library variables and to minimize the chances of conflict with symbol names in your application. Variable Description ------------------------------------------------------------ int _PL_beepfreq Specifies the frequency argument passed to tone by the beep function. Default value: 880. int _PL_beeplen Specifies the duration argument passed to tone by the beep function. Default value: 2. int _PL_breakflag Set by the hookints function's Ctrl- Break handler when the user presses <Ctrl-Break>. int _PL_color Internal color attribute. Set by vcolor. int _PL_colorsupport TRUE if the host display supports color. One of the values returned by getvconfig. int _PL_columns The number of screen columns. One of the values returned by getvconfig. int _PL_comoverflow Set to a non-zero value if the communications' receive buffer overflows. Set to 0 by comflush. int _PL_comtimeout Number of 18ths of a second allowed between characters by the serial communications' input and output routines. Set by comsettimeout and returned by comgettimeout. int _PL_editfill Character used by kbdedit to fill blank edit columns. Default value: '\xFA'. int _PL_errorbeep The beep function beeps only if this variable is non-zero. Set by seterrorbeep. 70 PICTOR User's Guide and Reference int _PL_escape TRUE if the last key returned by kbdread was the Escape key. This is the value returned by escpressed. char *_PL_helpcontext Pointer to the help topic string used by some library routines that pass it to helprun. Set by helpsetcontext and returned by helpgetcontext. int (*_PL_helpfunc)(); Points to helprun if help has been activated, or is set to NULL if help is not activated. This variable is set and cleared by helpopen and helpclose respectively. Library functions that access the help system check this variable to see if help is active. This allows these functions to access help without causing the help routines to be linked into your program if your program doesn't activate help. int _PL_lbcols Specifies the number of columns in the list box created by listbox. int _PL_lbcolwidth Specifies the width of each column in the list box created by listbox. int _PL_lbrows Specifies the number of rows in the list box created by listbox. int _PL_menurow Determines the screen row used for the pulldown menus. Default value: 1. int _PL_mode The current video mode. One of the values returned by getvconfig. int _PL_offset Screen offset used by library routines that write to the display. This variable is set by setvpos. It is used in combination with _PL_segment to calculated the screen address when writing to the display. int _PL_page The current video display page. One of the values returned by getvconfig. int _PL_pushedkey Variable to store the keystroke pushed by kbdpush. The variable is set to 0 by kbdread. int _PL_rows Number of screen rows. One of the values returned by getvconfig. int _PL_segment Display segment. This variable is used in combination with _PL_offset to calculate the screen address when writing to the display. One of the values returned by getvconfig. int _PL_shadowcolor Color attribute used to create window shadows. When a window is created with the WO_SHADOW attribute, this attribute is written along the bottom and right side of the window. The default value is foreback(WHITE, BLACK) (0x07). You may want to set this variable to foreback(BOLD+BLACK, BLACK) (0x08) for a 71 PICTOR User's Guide and Reference darker shadow, but note that some non- color systems cannot display bold attributes. int _PL_snowcheck TRUE if the activate display adapter is a CGA. One of the values returned by getvconfig. Set to FALSE by snowcheckoff. Warning: Setting this variable to TRUE can cause unpredictable results if the active display adapter is not CGA compatible. int _PL_statusrow Row used to display the status bar. Set by initstatus. int _PL_tabendedit If this variable is TRUE, kbdedit will act as though <Enter> was pressed when the user presses <Tab> or <Shift-Tab>. This variable is used by multiedit to allow the user to tab between edit fields. WINDOW *_PL_winhead Pointer to the active window or NULL if no windows are active. int _PL_wintab Specifies the tab displacement for tab characters written to windows. Default value: 8. 72